10장 나만의 명령어 만들기 (입문판)

원서: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 3가지만 기억하세요. 1. 자주 쓰는 긴 지시를 짧은 이름 하나로 부르는 법 (나만의 명령어) 2. 그 명령어를 "팀과 나눌지" "나 혼자 쓸지" 정하는 법 (스코프) 3. 명령어가 많아질 때 폴더로 깔끔하게 정리하는 법 (네임스페이싱) 지금은 이 세 가지만 천천히 따라 해도 충분합니다.

들어가기 전에

이 장은 "나만의 명령어 만들기"입니다. 원서에서는 이걸 커스텀 슬래시 커맨드라고 부릅니다.

커스텀 슬래시 커맨드: 자주 쓰는 긴 지시문을 파일 하나에 저장해 두고, /짧은이름 으로 불러 쓰는 기능. 일상 비유로는 휴대폰 단축번호와 같아요. 긴 번호 대신 "엄마" 한 번 누르면 전화가 걸리죠.

학습 목표 세 가지입니다. - 나만의 명령어가 무엇인지 설명한다. - 팀용 명령어와 개인용 명령어를 구분한다. - 폴더로 명령어를 정리하는 법을 따라 한다.

10-1 나만의 명령어 기본기

이런 적 있죠?

클로드 코드를 쓰다 보면 똑같은 지시를 매일 반복하게 됩니다.

"이 프로젝트 변경사항 보고 PR 만들어줘. 바뀐 파일 확인하고, 커밋 메시지로 제목 뽑고, 내용 요약해서 본문 써줘."

이 긴 문장을 어제도 쳤고, 오늘도 칩니다. 복사해 둔 메모를 찾아 붙여넣거나, 기억을 더듬어 다시 타이핑하죠. 짧으면 괜찮은데, 길어질수록 귀찮고 오타도 납니다.

바로 이 반복을 없애주는 게 나만의 명령어입니다. 한 번 저장해 두면, 다음부터는 /create-pr 같은 짧은 이름 하나로 끝납니다.

비유 먼저 (단축번호 이야기)

전화를 걸 때 매번 11자리 번호를 외워서 누른다고 생각해 보세요. 불편하죠. 그래서 우리는 자주 거는 번호를 "엄마", "회사"로 저장해 둡니다. 다음부터는 이름만 터치하면 전화가 걸립니다.

나만의 명령어가 딱 이겁니다.

여기서 새로 나온 말 하나만 짚고 갈게요. 프롬프트: 클로드에게 시키는 지시문, 한마디로 "이렇게 해줘"라고 적은 글. 마치 식당에서 종업원에게 건네는 주문서 같은 거예요.

어떻게 부르나 (기본 구조)

명령어를 부르는 모양은 이렇게 생겼습니다.

/<prefix>:<command-name> [arguments]

낯선 단어가 셋 보이죠. 하나씩 일상말로 바꿔 보면 간단합니다.

prefix(프리픽스)는 "접두사", 즉 앞에 붙는 꼬리표예요. 이건 다음 절(10-2)에서 자세히 다룹니다. arguments(아규먼트)는 "추가로 건네주는 정보"입니다. 주문할 때 "곱빼기로요" 한마디 덧붙이는 것과 같아요.

직접 따라 하기

명령어를 만드는 건 그냥 파일 하나 만드는 일입니다. 순서는 두 단계뿐입니다.

먼저 명령어를 담을 폴더와 파일을 만듭니다.

mkdir -p .claude/commands

그다음 create-pr.md 파일에 평소 치던 지시문을 그대로 적어 넣습니다.

이 프로젝트의 변경사항을 분석하고 PR을 만들어주세요.
- 변경된 파일 목록 확인
- 커밋 메시지로 PR 제목 작성
- 변경 내용을 요약해 PR 본문 작성

이제 클로드 코드 안에서 이렇게 부르면 끝입니다.

/project:create-pr issue-79

방금 저장한 긴 지시문이 자동으로 실행됩니다.

arguments는 똑똑하게 쓰입니다

위에서 issue-79를 같이 넘겼죠. 이건 "이 값을 정확히 여기에 넣어라" 하는 기계적 치환이 아닙니다. 클로드 코드가 맥락을 읽고 알아서 활용합니다.

비유하자면, 종업원에게 "79번 테이블 거요"라고 한마디 덧붙이는 것과 같아요. 종업원이 알아서 79번 테이블로 음식을 가져다주죠. 좌표를 일일이 안 찍어줘도 됩니다.

issue-79를 넘기면 클로드가 "아, 79번 이슈와 관련된 PR을 만들라는 거구나" 하고 맥락에 맞춰 씁니다.

잘못된 예 vs 올바른 예

명령어를 부를 때 가장 흔한 실수는 .md를 붙이는 겁니다.

잘못된 예:  /project:create-pr.md
올바른 예:  /project:create-pr

파일을 저장할 땐 create-pr.md로 저장하지만, 부를 땐 .md를 떼고 create-pr만 씁니다.

이럴 때 이렇게: "어? 명령어가 안 불러져요"라면, 부를 때 .md를 붙이지 않았는지 먼저 확인하세요.

한 걸음 더 ▸ arguments는 없어도 됩니다

arguments는 선택입니다. 안 넘겨도 명령어는 잘 돌아갑니다.

/project:create-pr        (추가 정보 없이도 OK)

추가로 알려줄 정보가 있을 때만 뒤에 붙이면 됩니다. 평소엔 짧게 이름만 불러도 충분해요.

여기까지 정리

• 명령어 파일은 꼭 .md로 저장한다.
• 부를 땐 .md를 빼고 파일명만 쓴다.
• arguments는 선택이다. 없어도 돌아간다.
• 넘긴 값은 클로드가 맥락을 보고 알아서 쓴다.

10-2 명령어를 어디에 둘까 (스코프)

이런 적 있죠?

명령어를 하나 만들어 잘 쓰고 있었어요. 그런데 옆자리 동료가 "그 명령어 나도 쓰고 싶은데 내 화면엔 안 보여"라고 합니다. 분명 만들었는데 왜 동료한테는 안 보일까요?

반대 상황도 있습니다. 나만 쓰는 개인 메모 정리 명령어를 만들었는데, 팀원 모두의 화면에 그게 떠 있습니다. "이거 누가 만든 거야?" 하고 다들 의아해하죠.

이 두 문제의 정답이 바로 스코프입니다. 스코프(scope): 이 명령어가 "어디까지 보이고 쓰이는지"를 정하는 범위. 한마디로 "누가 쓸 수 있냐"입니다.

비유 먼저 (회사 서랍 vs 집 서랍)

물건을 어디 서랍에 넣느냐로 누가 쓸지가 갈립니다.

• 회사 서랍에 넣으면 → 팀원 모두가 같이 씁니다.
• 집 서랍에 넣으면 → 나만, 대신 어느 사무실에 가도 가져다 씁니다.

명령어도 똑같이 두 서랍이 있습니다.

새 단어 하나 짚고 갈게요. ~(물결표): 내 컴퓨터의 "집"에 해당하는 홈 폴더를 가리키는 기호. 어느 프로젝트에 있든 나를 따라다니는 개인 공간이라고 보면 됩니다.

회사 서랍 — 프로젝트 명령어

팀과 함께 쓰는 명령어는 프로젝트 안의 .claude/commands/에 넣습니다.

여기서 깃(Git)은 코드 변경 이력을 저장·공유하는 도구입니다. 팀원이 깃으로 코드를 받아 가면, .claude/commands/ 안의 명령어도 같이 딸려 옵니다. (깃은 앞 장에서 다룬 내용을 떠올리면 됩니다.)

.claude/commands/create-pr.md    →  /project:create-pr
.claude/commands/run-tests.md    →  /project:run-tests
.claude/commands/review-code.md  →  /project:review-code

집 서랍 — 사용자 명령어

나 혼자, 그리고 어느 프로젝트에서나 쓰고 싶은 명령어는 홈 폴더의 ~/.claude/commands/에 넣습니다.

~/.claude/commands/analyze-code.md  →  /user:analyze-code
~/.claude/commands/explain.md       →  /user:explain

잘못된 예 vs 올바른 예

서랍을 헷갈리면 앞에서 본 "안 보여요" 문제가 생깁니다.

잘못된 예:  팀 전체가 쓸 CI 명령어를 ~/.claude/commands/ 에 저장
            → 동료 화면엔 안 보임 (집 서랍이라 나만 보임)

올바른 예:  팀 전체가 쓸 CI 명령어를 .claude/commands/ 에 저장
            → 깃으로 자동 공유, 동료도 보임

잘못된 예:  내 개인 메모 명령어를 .claude/commands/ 에 저장
            → 팀원 모두에게 쓸데없이 보임

올바른 예:  내 개인 메모 명령어를 ~/.claude/commands/ 에 저장
            → 나만, 어느 프로젝트에서나 사용

여기서 CI는 코드가 잘 도는지 자동으로 검사·빌드해 주는 작업을 말합니다. 팀이 함께 쓰는 대표적인 작업이라 프로젝트 명령어로 두기 좋습니다.

이럴 때 이렇게: "내 명령어가 동료한테 안 보여요"라면, 회사 서랍(.claude/commands/)이 아니라 집 서랍(~/.claude/commands/)에 넣은 건 아닌지부터 확인하세요. 10-1의 따라 하기 예제가 바로 회사 서랍(.claude/commands/)을 쓴 경우였습니다.

한 걸음 더 ▸ 빠르게 보는 비교표

원서/노트 기준 예시이며, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 확인하세요.

여기까지 정리

• 팀과 나눌 명령어 → .claude/commands/ (프로젝트 명령어, 접두사 /project:)
• 나만 쓸 명령어 → ~/.claude/commands/ (사용자 명령어, 접두사 /user:)
• 프로젝트 명령어는 깃에 담겨 자동 공유된다.
• 사용자 명령어는 한 번 만들면 어느 프로젝트에서나 쓴다.

10-3 명령어가 많아지면 (네임스페이싱)

이런 적 있죠?

명령어를 쓰다 보면 점점 늘어납니다. /project:create-pr, /project:review-pr, /project:run-unit-test, /project:run-integration-test, /project:deploy-staging...

한 서랍에 다 쌓여 있으니 이름이 길어지고, 비슷한 게 섞여 헷갈립니다. "테스트 관련 명령어가 뭐였더라?" 하고 목록을 한참 뒤지게 되죠.

이걸 폴더로 깔끔하게 묶는 게 네임스페이싱입니다. 네임스페이싱(namespacing): 명령어를 주제별 폴더에 나눠 담아 그룹으로 정리하는 것. 한마디로 "서랍 안에 칸막이 넣기"입니다.

비유 먼저 (서류 캐비닛 이야기)

서류 100장이 한 서랍에 뒤섞여 있으면 원하는 걸 찾기 힘듭니다. 그래서 우리는 "github 관련", "test 관련", "deploy 관련" 폴더로 나눠 담죠. 그러면 "아, 테스트 서류는 test 폴더지" 하고 금방 찾습니다.

폴더가 곧 그룹이 됩니다

규칙은 딱 하나입니다. 하위 폴더를 만들면, 그 폴더 이름이 그대로 그룹 이름(네임스페이스)이 됩니다. 부를 땐 콜론(:)으로 이어 붙입니다.

정리 안 했을 때와 정리했을 때를 나란히 볼게요.

정리 전:  /project:create-pr
          /project:run-unit-test
          /project:deploy-staging
          → 이름이 길고 그룹이 안 보임

정리 후:  /project:github:create-pr
          /project:test:unit
          /project:deploy:staging
          → 그룹(github / test / deploy)이 한눈에 보임

폴더 구조로 보면 이렇게 생겼습니다.

.claude/commands/
├── github/
│   ├── create-pr.md     →  /project:github:create-pr
│   └── review-pr.md     →  /project:github:review-pr
├── test/
│   ├── unit.md          →  /project:test:unit
│   └── integration.md   →  /project:test:integration
└── deploy/
    └── staging.md       →  /project:deploy:staging

직접 따라 하기

github 폴더를 만들고 그 안에 명령어를 넣어 봅니다.

mkdir -p .claude/commands/github

그리고 github/create-pr.md 파일에 지시문을 적습니다.

현재 브랜치의 변경사항을 분석해 GitHub PR을 만들어주세요.
- 변경 파일 목록 확인
- 커밋 히스토리 분석
- PR 제목과 본문 자동 작성

이제 부를 땐 폴더 이름을 콜론으로 끼워 넣습니다.

/project:github:create-pr

경로와 부르는 이름은 1:1로 대응합니다

폴더 위치만 보면 어떻게 부를지 바로 알 수 있습니다.

읽는 법은 간단합니다. 앞 꼬리표(project/user)는 어느 서랍인지(10-2), 가운데 폴더 이름은 그룹, 맨 끝이 파일 이름입니다.

잘못된 예 vs 올바른 예

폴더로 나눴는데 부를 때 콜론을 빼면 안 됩니다.

잘못된 예:  /project:github-create-pr   (폴더를 하이픈으로 이어 붙임)
올바른 예:  /project:github:create-pr   (폴더는 콜론으로 구분)

이럴 때 이렇게: 명령어를 폴더에 넣었는데 안 불러진다면, 폴더 이름과 파일 이름 사이를 콜론(:)으로 이었는지 확인하세요.

한 걸음 더 ▸ 사용자 명령어도 폴더로 묶입니다

네임스페이싱은 회사 서랍(프로젝트)만 되는 게 아니라 집 서랍(사용자)에서도 똑같이 됩니다.

여기까지 정리

• 하위 폴더를 만들면 그 이름이 자동으로 그룹(네임스페이스)이 된다.
• 부를 땐 /<접두사>:<그룹>:<명령어> 형태로 콜론을 이어 쓴다.
• 프로젝트 명령어든 사용자 명령어든 둘 다 폴더로 묶을 수 있다.
• 관련 명령어끼리 같은 폴더에 모으면 찾기가 쉬워진다.

손으로 풀어 보기

문제 1 (쉬움)

아래 명령어가 가리키는 파일의 전체 경로는?

/project:github:create-pr

문제 2 (보통)

다음 세 가지를 만족하는 파일 구조를 직접 짜 보세요.

• 팀 전체가 쓰는 코드 리뷰 명령어
• 나만 쓰는 일일 보고서 명령어
• GitHub 관련 명령어는 폴더로 묶기

팀 공유 (프로젝트 명령어)
.claude/commands/review-code.md          → /project:review-code
.claude/commands/github/create-pr.md     → /project:github:create-pr
.claude/commands/github/review-pr.md     → /project:github:review-pr

나만 쓰기 (사용자 명령어)
~/.claude/commands/daily-report.md       → /user:daily-report

문제 3 (한 걸음 더)

회사에서 이런 일이 생겼습니다. 원인과 해결책을 적어 보세요.

"동료 A가 만든 /project:deploy:staging 명령어가 동료 B 화면엔 안 보인다."

한눈에 보는 이 장 요약

• 나만의 명령어 = 자주 쓰는 긴 지시를 .md 파일로 저장해 /짧은이름으로 부르는 기능. (단축번호)
• 저장할 땐 .md, 부를 땐 .md 빼고. arguments는 선택, 클로드가 맥락 보고 활용.
• 회사 서랍 .claude/commands/(/project:) → 팀 공유. 집 서랍 ~/.claude/commands/(/user:) → 나만, 모든 프로젝트.
• 폴더로 묶으면 그 이름이 그룹(네임스페이스). 부를 땐 콜론(:)으로 이어 /project:github:create-pr.

새로 배운 말 정리

다음 장 예고: 다음 장에서는 클로드 코드의 또 다른 활용법을 이어서 다룹니다. 지금 몰라도 됩니다.